home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Contributed / SpriteWorld / Documentation / SpriteWorld Code Standards < prev    next >
Encoding:
Text File  |  2000-10-06  |  4.9 KB  |  151 lines  |  [TEXT/CWIE]
  1. /*
  2.  
  3. SPRITEWORLD CODE STANDARDS
  4.  
  5. In order to help keep the SpriteWorld code consistent, here are some guidelines that
  6. contributors should try to follow when writing code for SpriteWorld. This is not a "do or die" 
  7. list of rules; if you do not follow them, we will not throw your code out for that reason
  8. alone. However, if it's not much more work for you, look over the suggestions below and try
  9. to follow them when writing code for SpriteWorld. It will help the current maintainer, as
  10. he won't have to clean up your code later to make it consistent with the rest of SpriteWorld.
  11.  
  12. Here are the guidelines:
  13.  
  14. 1) Functions should begin with comments containing the function's name as shown 
  15. in the examples below. There should be a single tab between the "//" and the beginning  
  16. of the function's name. If you change a function's name, remember to update the name
  17. in the comments as well.
  18.  
  19. 2) There should be two blank lines between functions, also shown below. In addition,
  20. there should be one blank line between the comments preceding the function, and the
  21. function itself.
  22.  
  23. (more rules after the examples below)
  24.  
  25. */
  26.  
  27. ///--------------------------------------------------------------------------------------
  28. //    SWSetSpriteMoveTime
  29. ///--------------------------------------------------------------------------------------
  30.  
  31. SW_FUNC void SWSetSpriteMoveTime(
  32.     SpritePtr srcSpriteP,
  33.     long timeInterval)
  34. {
  35.     SW_ASSERT(srcSpriteP != NULL);
  36.     srcSpriteP->moveTimeInterval = timeInterval;
  37. }
  38.  
  39.  
  40. ///--------------------------------------------------------------------------------------
  41. //    SWSetSpriteCollideProc
  42. ///--------------------------------------------------------------------------------------
  43.  
  44. SW_FUNC void SWSetSpriteCollideProc(
  45.     SpritePtr srcSpriteP,
  46.     CollideProcPtr collideProc)
  47. {
  48.     SW_ASSERT(srcSpriteP != NULL);
  49.     srcSpriteP->spriteCollideProc = collideProc;
  50. }
  51.  
  52.  
  53. /*
  54.  
  55. 3) Functions should use SW_ASSERT where practical to ensure values passed to the function
  56. as parameters, and used from structures, are what they are assumed to be. However, these
  57. should only be used to avoid crashes or other bad behaviour when the programmer makes
  58. a mistake that should be fixed. These should not be used in situations that are valid
  59. in a program that works correctly. (i.e. don't use assertion errors as the only way of
  60. providing the user with an error message telling them they're running in the wrong depth.)
  61. Note that assertions could be left completely out for final builds.
  62.  
  63. 4) When adding comments to the code, the comments should use "//" when possible,
  64. instead of "/*". In addition, the comments should be one tab farther to the right 
  65. than the code that follows:
  66.  
  67. */
  68.  
  69.         // Set the monster to super-evil mode
  70.     monsterP->mode = kSuperEvil;
  71.  
  72. /*
  73.  
  74. 5) The preferred style for braces is the following:
  75.  
  76. if (stuff)
  77. {
  78.     whatever;
  79. }
  80.  
  81. not:
  82.  
  83. if (stuff) {
  84.     whatever;
  85. }
  86.  
  87. 6) Preferred tab space size is 4 spaces per tab.
  88. Leave the tab characters in, instead of substituting them with space runs.
  89.  
  90. 7) Anders recommends using the "ProFont 9 pt" font for the CW editor,
  91. and an off-white background color (R:100% G:100% B:80% is a nice yellow).
  92. As well as all syntax-coloring on, incl. Browser Coloring and Custom Keywords.
  93. Makes stuff much easier to see, and easier on the eyes.
  94.  
  95. 8) You can use "#pragma mark -" to separate sections of code.
  96. This gives a divider in CodeWarrior's function popup menu.
  97.  
  98. 9) All exported globals start with "g", all constants with "k".
  99. Local declarations should be declared as "static", and NOT appear in any public headers.
  100.  
  101. 10) All public SpriteWorld functions should start with either "SW..." or "BlitPixie...Proc".
  102. All exported globals should start with "gSW..." and be declared as "extern" in a header file.
  103.  
  104. 11) Macros should be in UPPER_CASE_WITH_UNDERSCORES format, and preferrably start with "SW_"
  105. Simple constants are still given a "k" prefix, as above. Do NOT use the "const" keyword.
  106.  
  107. 12) Explanation of SpriteWorld's elaborate public headers:
  108.  
  109. */
  110.  
  111.     // a) this is known as a "shield", and used to avoid including the same header twice,
  112.     // has the same effect as "#pragma once", since that pragma might not be supported?
  113. #ifndef __SPRITEWORLD__
  114. #define __SPRITEWORLD__
  115.  
  116.     // b) this declaration keeps the C++ name wrangler from messing up the function names,
  117.     // if we are using SpriteWorld from C++ while still compiling the library as C.
  118. #ifdef __cplusplus
  119. extern "C" {
  120. #endif
  121.  
  122.     // c) this keeps the alignment on 68k (2-byte) boundaries to be compatible with Pascal,
  123.     // it also makes structures the same cross-platform, since they're padded the same way.
  124. #if PRAGMA_ALIGN_SUPPORTED
  125. #pragma options align=mac68k
  126. #endif
  127.  
  128.  
  129.  
  130.  
  131.     // these declarations at the end of the header file just match/reset the ones above.
  132. #if PRAGMA_ALIGN_SUPPORTED
  133. #pragma options align=reset
  134. #endif
  135.  
  136. #ifdef __cplusplus
  137. }
  138. #endif
  139.  
  140. #endif /* __SPRITEWORLD__ */    
  141.  
  142. /*
  143.  
  144. 12) Don't forget to do something fun once in a while,
  145. like play the games you are supposed to be writing :-)
  146.  
  147.  
  148.  
  149. These guidelines written by Vern Jensen and Anders F Björklund in 1999.
  150.  
  151. */